The eclectic CDEF Collection is a set of 2 CDEFs (control definition functions), the Celsius CDEF and the Gauss CDEF.
CDEF stands for "control definition function": it is a way to define the appearance and the behavior of custom controls. Custom controls may be dials, gauges, sliders, and so on. CDEFs may be used by almost every Macintosh software and by practically every development environment and programming language.
The Celsius CDEF implements a thermometer- or barber pole-style progress bar similar to that used by the Finder in the Copy or Find windows. Additional options allows you to honor custom colors stored in 'cctb' resources, to draw the bar always in the active look ignoring deactivations, and finally to display the bar with a 3D-like "inset" effect, as shown in the develop 15 article "Working in the Third Dimension".
The Gauss CDEF draws application-specified blocks of text. It can draw simply the control's title, append a numeric value to it or draw a block of text up to 32K set up by the calling application. Optionally the Gauss CDEF can also honor 'cctb' resources, draw the text with the owning windows' text font, size and style, and draw a 3D-like effect (inset or raised).
The eclectic CDEF Collection consists of
- two CDEFs: the Celsius CDEF and the Gauss CDEF
- two 'stubs' to allow source-level debugging of the CDEFs: StubCDEF and JumpCDEF
- some utility routines
- a demonstration application for the CDEFs
The eclectic CDEF Collection is written by:
Sebastiano Pilla
Viale dei Mille 20
31100 Treviso (Italy)
<mailto:case@tvol.it>
Substantial contributes to these CDEFs came from Andrew Regan, Chris Larson, Peter Lewis and Jim Stout.
Distribution status and conditions for use
------------------------------------------
The eclectic CDEF Collection is distributed as freeware, meaning that it's copyrighted freely available software.
I grant users of the eclectic CDEF Collection permission to use the CDEFs, the source code, or modified versions in any Macintosh software product, provided that the following conditions are met:
1) This grant is non-exclusive
2) I keep the copyright on the original source code
3) Any redistribution of the package must be in the original form, with all source code,
object code and accompanying documentation
4) The package cannot be included in software collections distributed for profit without
obtaining my prior written permission
The following condition is optional:
1) You give me credit either in the About box or the documentation of the software
product in which you use any CDEF of this collection
How do I use a CDEF?
--------------------
Let's say you want to create a custom control for your application. Usually the only thing you need to do is assign a special value to the ProcID field of a 'CNTL' resource. The value for this field is calculated as:
(CDEF resource ID * 16) + variation code
Some CDEFs (including the Gauss CDEF) require other special settings; you need to consult the documentation for these CDEFs to see what is needed.
Road map
--------
The eclectic CDEF Collection package is organized as follows:
- CDEF Utilities: contains utility routines for implementing CDEFs and two 'stubs' to
allow source-level debugging of CDEF resources into the normal context of applications,
with your favorite debugger
- CDEFTester Folder: contains the CDEFTester demonstration application, with its
documentation and source code
- Celsius CDEF Folder: contains the compiled code of the Celsius CDEF, its documentation
and its source code
- Gauss CDEF Folder: contains the compiled code of the Gauss CDEF, its documentation
and its source code
Each CDEFs has extensive documentation: please read carefully the files "Celsius CDEF Info" in the Celsius CDEF Folder and the file "Gauss CDEF Info" in the Gauss CDEF Folder.
Understanding and modifying the CDEF code
-----------------------------------------
Provided that you honor the conditions listed above, you can freely modify the source code (even port it to other programming languages) and distribute your modified versions. I always appreciate receiving your modifications.
I would like to provide some insights on the code, to help you understanding it.
- The code, while not straightforward in some places, is reasonably well commented. If you plan to make your code available to other people, try to explain in the comments the strategy you adopt, especially in the tricky sections.
- Though not essential on the 68K-only THINK Pascal compiler, I based the code on a recent version of the Apple Universal Interfaces for Pascal and I used UPPs in about all situations. This should provide easier recompilations with other development environments.
- I tried to write the code with an uniform style convention. All constants are prefixed with the lowercase letter 'k', all record fields are prefixed with the lowercase letter 'f'; regarding routine parameters, the prefix 'in' indicates an input-only parameter, the prefix 'out' indicates an output-only parameter (i.e. whose value on entry is not significant to the routine), and the prefix 'io' indicates an input-output parameter (i.e. whose value on entry is significant and may be modified by the routine).
- I avoided global variables at all since they cause all sort of headaches in code resources. Instead I stuff a handle into the contrlData field of the control passed to the CDEF main entry point to store all the "global" data here. Even when I need to use black and white patterns I get them thru Resource Manager calls, not by using the QuickDraw globals. The advantages of this approach definitely overcome the limitations that applications cannot use this field at all.
Comments
--------
I wrote these CDEFs because I wanted to display a window when one of my applications scan the mounted hard drives looking for some particular files and folders. I thought that this situation could be handled in a very simple and clean fashion with two custom controls, one for informing the user of the scan status, the other for showing the progress of the operation. Of course, the project has grown out of control pretty quickly...
Here's a (more or less) random collection of notes and facts I've built in the development of these CDEFs.
- The definition of ExtendedToString in the latest PInterfaces and CIncludes contains a bug. It currently is
FUNCTION ExtendedToString (VAR x: extended80;
{CONST} VAR myCanonical: NumFormatString;
{CONST} VAR partsTable: NumberParts;
VAR outString: Str255): FormatStatus;
This contradicts Inside Macintosh: Text, WHERE THE x PARAMETER IS NOT A VAR PARAMETER. It should be
{CONST} VAR x: extended80;
if your compiler supports the {CONST} VAR crap, and simply
x: extended80;
if your compiler it is not brain-damaged. The fix for the CIncludes is similar.
I filed Bug #115753 against it with the Apple Bug Report Center.
- I used GWorlds to implement flicker-free drawing in most situations and I didn't bothered to check for GWorld availability. This may cause unexpected crashes on machines without Color QuickDraw, like the 68000-based Mac Plus, SE, Classic, Portable, PowerBook 100. However, Inside Macintosh VI points out that if these machines run under System 7 these routines are available with the use of extended GrafPorts.
- To honor the colors set in 'cctb' resources, the CDEFs call GetAuxiliaryControlRecord to access the auxiliary color table. I've spent a whole day tracking a nasty bug before I realized that an 'ictb' resource in a dialog box trashed the control color table, so I implemented a safety net. My CDEFs check for NIL handles to auxiliary control records and to color tables, and lock the color tables before accessing them. If one of these checks fails, the CDEFs revert to draw the 'standard' colors instead of crashing with Bus Errors and such amenities.
- Why I named the CDEFs that way?
Celsius CDEF: often a progress bar is indicated as "thermometer-style" bar, and the Celsius scale is the thermometric scale we use in Italy.
Gauss CDEF: originally this CDEF was designed to be used as a counter, so I thought about when the German mathematician C. F. Gauss in school surprised his professor by quickly summing all the integer numbers from 1 to 100, having rediscovered the formula by himself.
